using System.Collections.Generic;

namespace Rhinestone.Domain
{
    /// <summary>
    /// The <see cref="IWorkItemsService"/> interface defines a contract that consumers
    /// can use to manage work items in <see cref="Rhinestone"/>
    /// </summary>
    public interface IWorkItemsService
    {
        /// <summary>
        /// Gets a work item that matches the specified id.
        /// </summary>
        /// <param name="workItemID">int. The unique id of the work item to return.</param>
        /// <returns>A <see cref="WorkItem"/> instance that matches the specified id, or a null
        /// reference if no WorkItem with the specified id exists.</returns>
        WorkItem GetWorkItemByID(int workItemID);

        /// <summary>
        /// Gets all work items belonging to a project.
        /// </summary>
        /// <param name="project">The <see cref="Project"/> instance whose work items should be returned.</param>
        /// <returns>Gets a <see cref="IEnumerable{T}"/> that can be used to enumerate over all work items 
        /// in the specified project.</returns>
        IEnumerable<WorkItem> GetProjectWorkItems(Project project);

        /// <summary>
        /// Gets all work items recently added or updated in all projects.
        /// </summary>
        /// <param name="count">int. The total no of recent work items to return.</param>
        /// <returns>A <see cref="IEnumerable{T}"/> that can be used to enumerate over all recently added or 
        /// modified work items, irrespective of the project they belong to.</returns>
        IEnumerable<WorkItem> GetRecentWorkItems(int count);

        /// <summary>
        /// Gets all work items recently added or updated for a project.
        /// </summary>
        /// <param name="project">The <see cref="Project"/> instance whose work items should be returned.</param>
        /// <param name="count">int. The total no of recent work items to return.</param>
        /// <returns>Gets a <see cref="IEnumerable{T}"/> that can be used to enumerate over all recently added
        /// or modified work items in the specified project.</returns>
        IEnumerable<WorkItem> GetRecentProjectWorkItems(Project project, int count);

        /// <summary>
        /// Gets all work items that have been assinged to a user.
        /// </summary>
        /// <param name="user">The <see cref="IUser"/> instance whose work items shold be retrieved.</param>
        /// <returns>A <see cref="IEnumerable{T}"/> that can be used to enumerate over all work items that
        /// are assigned to the specified user.</returns>
        IEnumerable<WorkItem> GetWorkItemsAssignedToUser(IUser user);

        /// <summary>
        /// Gets all work items that have been submitted by a user.
        /// </summary>
        /// <param name="user">The <see cref="IUser"/> instance whose work items should be returned.</param>
        /// <returns>A <see cref="IEnumerable{T}"/> that can be used to enumerate over all work items that
        /// are submitted by the specified user.</returns>
        IEnumerable<WorkItem> GetWorkItemsSubmittedByUser(IUser user);

        /// <summary>
        /// Saves a work item.
        /// </summary>
        /// <param name="workItem">The <see cref="WorkItem"/> instance to save.</param>
        void SaveWorkItem(WorkItem workItem);

        /// <summary>
        /// Deletes a work item.
        /// </summary>
        /// <param name="workItem">The <see cref="WorkItem"/> instance to delete.</param>
        void DeleteWorkItem(WorkItem workItem);
    }
}